This file is best viewed in SimpleText. It contains an exact copy of the help available from within Analog Helper, however in this format it can be viewed separately, or printed.
Introduction and Help
Analog Helper is a graphical configuration tool for Analog, which is a free program to analyze the logfiles from your web server. Analog Helper lets you control and preview the results of hundreds of settings and means you need not touch the complex syntax of Analog's configuration files.
Analog itself was written by Stephen Turner and ported to Mac by Jason T. Linhart. It tells you which pages are most popular, which countries people are visiting from, which sites they tried to follow broken links from, etc... It is the fastest and most flexible such tool available.
Analog Helper can also configure Report Magic for more advanced HTML reporting, automatically configuring Analog to output data for Report Magic, writing Report Magic's config file and running Report Magic. However, you need not be aware of any of this process; simply set up your analysis as required in Analog Helper, and it will do the rest of the work.
Analog Helper can also import your old Analog configuration files so that you have an easier way to adjust existing configurations. But Analog Helper extends Analog's functionality by allowing multiple configurations to be maintained, integrating Report Magic and optionally splitting analyses up into separate daily, weekly, monthly, or annual reports.
Analog Helper contains context-sensitive help for all of the available options, which can be toggled from the Help menu. If you do not know what a configuration option does, move the mouse over it and a description with examples will appear below. Analog Helper also contains more detailed help, available from the Help menu. For details on Analog itself, you may want to consult the documentation which comes with the Analog download.
We hope you find Analog Helper useful. If there are any queries, comments or suggestions, please contact us at support@sigsoftware.com.
Sig Software
http://www.sigsoftware.com/
Payment and Registration
Analog Helper is freely distributed as trial software. You are permitted to evaluate it for 28 days before discarding it, or purchasing a license. When Analog Helper is purchased, all of the output reports will be enabled.
Licensing
You must purchase one license for each computer on which Analog Helper is used. Licenses can be purchased with the enclosed Register Analog Helper program, using a page on the World Wide Web, or via telephone. Payment may be made by cash, check, VISA, MasterCard or American Express.
Pricing
Current pricing is $25 for a single-CPU license. There is excellent discount pricing available for multiple-license purchases; the Register Analog Helper application includes pricing for up to 20 licenses - for higher-volume pricing, please contact us at pricing@sigsoftware.com.
Purchasing online (easiest)
• Click Purchase Online… in the about box or go to http://order.kagi.com/?BX
• Wait for your web browser to load up the page.
• Select how many of which products you wish to purchase.
• Enter your name, address and email address in the areas provided (all are required).
• Please enter any additional comments in the space provided.
• Follow the instructions on the web page to enter your credit-card details.
Purchasing via email
• Click Purchase Alternative… in the about box or run the Register NameCleaner program.
• Enter your name, address and email address in the areas provided (all are required).
• Select how many of which products you wish to purchase.
• Please enter any additional comments by clicking the speech bubble next to the product name.
• Select the VISA, MasterCard or American Express payment method and enter your card details.
• Click the Copy… button to copy out the text for emailing.
• Create a new email message in your email software.
• Choose Paste from the Edit menu.
• Address the message to shareware@kagi.com and send it.
Purchasing over the telephone
• Call (US) 510 658-5244, available 10am to 5pm PST weekdays and at some other times.
• Follow the instructions on the telephone.
• When asked, specify how many, of which products you wish to purchase.
• When asked, state your name, address and email address clearly (all are required).
• Please note that telephone orders carry an additional handling charge of $5.
Purchasing via fax
• Click Purchase Alternative… in the about box or run the Register NameCleaner program.
• Enter your name, address and email address in the areas provided (all are required).
• Select how many of which products you wish to purchase.
• Please enter any additional comments by clicking the speech bubble next to the product name.
• Select the VISA, MasterCard or American Express payment method and enter your card details.
• Click the Print… button to print out the form for faxing.
• Fax the printed form to (US) 510 652-6589.
Purchasing by mail (slowest)
• Click Purchase Alternative… in the about box or run the Register NameCleaner program.
• Enter your name, address and email address in the areas provided (all are required).
• Select how many of which products you wish to purchase.
• Please enter any additional comments by clicking the speech bubble next to the product name.
• Select the Check, Cash, VISA, MasterCard or American Express payment method.
• If you are purchasing by cash, select the currency you wish to pay in.
• If you are purchasing by credit-card, enter your card details.
• Click the Print… button to print out the form to sent with your payment.
• Send to : Kagi, 1442-A Walnut St PMB #392-BX, Berkeley, CA 94709-1405, USA.
After you have purchased
As soon as your payment has been processed by Kagi, you will automatically receive an email with the subject Thanks for your Payment. Within 24 hours after this, you will be emailed your license code or contacted if there is a problem (a human has to check your details before sending a license). If you wish to trace an order, please contact support@sigsoftware.com.
Getting Started with Analog Helper
To start using Analog Helper, either use the blank analysis that comes up when it is opened, or import a previous .cfg file using the Import command in the File menu. On the left is a list of panels of options that can be edited. The first three contain global settings for an analysis, described in the next section. Each of the others represents one of the reports that Analog can produce and are described in a separate section.
To actually perform an analysis, click the Analyze button or hit return. To only write Analog's config file without performing the analysis, click Write Config. The analysis can be performed later by running Analog manually. The On Open menu lets you set which action Analog Helper should perform on the analysis file when it is opened from the Finder. To stop this happening when the file is opened, hold down any modifier key (shift, option, command, control) or open the analysis from within Analog Helper by choosing Open from the File menu.
The Use Nav Services setting in the Edit menu controls whether files and folders should be chosen using Apple’s Navigation Services (included in Mac OS 8.5 but available for OS 7.5.5 or later). Navigation Services have been known to cause problems with some setups, so switch this setting off if you are experiencing any.
This panel is mainly for setting which log files you would like Analog to analyze. Add individual files or entire folders of files to this list using drag-and-drop or by clicking the Add File / Folder button. Log files within a selected folder can also be filtered by name or last modified date.
This panel also contains other options, described by context-sensitive help but please note that if multiple reports are being created using the Create Reports option, the Date from value (and optionally the Date to) should also be set, otherwise Analog Helper will have to make a sensible, but probably wrong, guess of the overall time period to analyze.
Output Report
This panel contains various options connected to the final report file, which can be in Text Only, Basic HTML, Advanced HTML or Computer-readable format. The panel displays an explanation of each of these options. Set the Report Out File to the name and location you want. The Viewing Program sets which program the final report will be made a document of and therefore what it will be opened in if Open after Analysis is on.
For Basic HTML reporting, the Image Directory is a relative path from the output report location to the images required by the report. Ensure you have a copy of the contents of Analog's images folder in this location, otherwise graph bars and other pictures will not show up. For Advanced HTML reporting, the same applies for the three .gif files in Report Magic's folder, although you can leave the Image Directory blank to automatically have them copied into the required location.
Note: if you switch on domain name lookups in the Domain name mode menu, be aware that analyses will probably take at least 10 times longer than otherwise.
Inclusions / Exclusions
This panel contains several rule lists (see next section for how rule lists are applied). The three under Filter log entries by allow you to perform an analysis on only a part of the requests made to your web site. You can restrict the analysis to the actual files requested, to the URL of the referring page, or to the address of the requesting host.
The two under Keep arguments for let you set which requests and which referring URLs have their arguments (that's the section of the URL after the '?') kept for analyzing. If the argument is dropped, two items such as "/cgi-bin/search?info" and "/cgi-bin/search?contact" will be analyzed as identical.
The two under Add report links for determine which requests and referrers in their respective reports are given HTML links to their actual pages.
The Pages rule list lets you set which file names would qualify as referring to a web page (as opposed to an image or CGI script) - you can usually leave this as it is.
The Analog Commands list lets you add any additional commands which will be written out directly at the end of Analog's config file. This way, you can use any of the few Analog features that Analog Helper does not support, or override any of the commands which Analog Helper outputs. The Magic Commands list does the same thing for Report Magic.
Include / Exclude Rule Lists
All Include / Exclude rule lists are interpreted in the same manner. The order of the rules in the list does make a difference, and the algorithm applied is as follows : To decide whether an item should be included, the last rule that matches the item is used. If, however, the item matched none of the rules, it is included if the first rule was an Exclude, and excluded if the first rule was an Include. Here is an example :
(1) Include : A*
(2) Exclude : *N*
(3) Include : G*
For this rule list, the following items would be included : ALPHA (matches 1), GAMMA (matches 3), GAIN (matches 2, 3). The following items would be excluded : BETA (matches none, so excluded since first rule was an Include), AGAIN (matches 1, 2), NAG (matches 2).
As you may have noticed, you can use the "*" character as a wild card in a rule and it will match any series of zero or more characters. For example, the rule A*ND* would match AND, ABANDON and ANDES.
For all rule lists where it would make sense, you can use the keyword "pages" to refer to all page files (where the rules for determining what qualifies as a page is set in the Pages section of the Inclusions / Exclusions panel).
Lastly, for several of the reports, you can also add a Sub Rule (or Sub-Include). These are used in hierarchical reports; see the next section for more details.
Reports and Graphs
The reports to be output can be switched on and off by clicking on the right next to the name of the report. The reports can be reordered by dragging vertically. Each report contains a different set of relevant options; all possibilities are listed here below (in alphabetical order) :
Add Include / Exclude : Click one of these buttons to add a rule to determine which rows are shown in the report. See the previous section for help on using rule lists. Note: the Normal limit setting may still exclude a row that would be included based on the rule list.
Add Sub Rule : In hierarchical reports, you can choose which sub-items are shown as separate rows in the report. A sub rule might be a sub-directory, a sub-domain, a sub-file type or a sub-browser. You can use wild cards here as you would for other rules. Note: the Sub-row limit setting may still exclude a row that would be included based on the rule list.
Argument limit : This specifies the limit on which argument rows should be shown in the report (i.e. where a separate row is shown with an URL's arguments). It works in the same way as Normal limit; see that section for more information.
Columns : This pop-up menu lets you switch columns on and off in the report's graph. Note: not every column will be available for every report type.
Graph by : This specifies which statistic the graph bars (shown in red in the Sample) should be based on.
Maximum number of rows : This specifies a maximum number of rows to show in the graph.
Normal limit : This specifies the limit on which rows should be shown in the report. You can choose how this should be calculated, based on a minimum number of pages, bytes or requests, a minimum percentage of the total pages, bytes or requests or a minimum percentage of the row with the most pages, bytes or requests. For these three options, Analog Helper will automatically pick (and show you) whether it will use pages, bytes or requests depending on the Sort by setting. You can also simply specify a maximum number of rows to include, or to include rows which have a last access date after a specified date.
Sample : This is an example of the report's output, based on random fictional data, as it would appear in a Basic HTML report. You can drag columns within the Sample area to reorder them - use the Columns menu to add or remove columns. The Sample area will not show the include / exclude rule list or limits being applied, however it does show the result of the Columns, Graph by, Sort backwards and Sort by settings.
Sort backwards : This toggles whether a report should have the order of its rows reversed.
Sort by : This specifies the method which should be used for sorting the rows of the report. This setting may also affect the
limit settings.
Sub-row limit : This specifies the limit on which sub-rows should be shown in the report (i.e. where a separate row is shown for a sub-directory, sub-browser, etc...). It works in the same way as Normal limit; see that section for more information.
Frequently Asked Questions
What version of Analog does Analog Helper require?
Analog Helper needs version 3.0 of Analog or later. It will automatically prompt you if a copy of this is not found on your disk. Version 1.2 of Analog Helper also fully supports Analog 4. If you are using Analog 3, some of the configuration options will be ignored.
What can I do with my old .cfg files?
Analog Helper can import these, using Import from the File menu. A few of the lines in your config file may not be imported, and you will receive a full summary of the import operation when it is completed. You can drag information out of this report onto the desktop as a clipping file.
Why can't Analog Helper important all the lines of my .cfg files?
A few commands in Analog config files are overridden or configured differently in Analog Helper. These include the SUBSORTBY commands (which Analog Helper automatically maps to the non-hierarchical setting), input and output files (which Analog Helper stores references to in its own way) and warning and debug settings (which Analog Helper sets automatically).
How do I manage multiple virtual domains?
This depends on how you have you web server configured to write the logs for the separate domains. If it actually records the virtual host as a separate field in log files, you should add the command VHOSTINCLUDE www.mydomain.com to the Analog Configuration Commands section in the Inclusions / Exclusions panel.
However, if it logs requests in made-up directories to mimic the different virtual domains, you should use the Filter log entries by Requested file setting in the Inclusions / Exclusions panel to only include requests from the desired virtual domain. (In this case, also add a Sub-Rule to the directory report to include the real directories on your web site inside the made-up directories).
What about configuration commands Analog Helper doesn't support?
In the Inclusions / Exclusions panel, you can add any extra commands you need in the Analog Commands section. These will be written at the end of the analog.cfg file.
What about other languages?
Analog Helper supports all the languages that can be accessed using the LANGUAGE command for version 3.0. If you want to use a different language, or a langfile, add the command manually in the Analog Commands section of the Inclusions / Exclusions panel.
Will I lose my current analog.cfg file?
No. Analog Helper is very careful not to overwrite your current analog.cfg file unless it was created by Analog Helper itself. If an analog.cfg file was found by Analog Helper which it had to remove, the file will have been renamed analog.cfg.old and will be in its original location.
What happens with manconf.cfg?
As before, Analog will automatically read the manconf.cfg file after it has read the configuration set up by Analog Helper. So you can continue to use manconf.cfg to contain overriding settings or lists of aliases.
Are aliases supported?
Analog Helper does not currently support input or output aliases (which let you map certain values to others in order to group them or make them more readable). However, aliases will not be lost if you import a .cfg file, and will be added to the Analog Configuration Commands section of the Inclusions / Exclusions panel. We recommend you put aliases into the manconf.cfg file which Analog always reads last so that they are accessible to all your configurations.
How does multiple report generation work?
If you choose one of the options from the Create Reports menu of the Input Files panel, Analog Helper will automatically step through all the chosen time periods, generating a separate output report file for each one. These will be named as the Report File in the Output Report panel, but will be prefixed with the relevant date.
How do I edit an Analog Helper file without it automatically analyzing?
You can hold down one of the modifier keys (shift, command, option, control) when you open the file, or you can open it by choosing Open from the File menu instead of opening it from the Finder. Once the file is open, you can switch off automatic analysis using the On Open menu at the bottom of the configuration window.
How can I set up Analog Helper for scheduling?
Scheduling is not built-in to the current version of Analog Helper. However, all you need to set up a scheduled analysis is to have some other scheduling program (e.g. CRON) open the Analog Helper analysis file at the required intervals. If the Analog Helper analysis file is set to Analyze automatically, it will perform the analysis every time it is opened.
How can I include or exclude whole directories in my report?
In the Requested file section of the Inclusions / Exclusions panel, enter rules such as Include : /pub/* or Exclude : /private/*.
Any distribution of Analog Helper must include this file. No responsibility about Analog Helper's functionality or integrity is implied. This document and Analog Helper are copyright of the author. Other trademarks are copyright of their respective owners.
